Sélection des paramètres

Cette section présente les bases de la sélection d’un paramètre (en plus d’un indicateur) pour une requête API.

Récapitulatif des points de terminaison et des indicateurs

Comme indiqué dans le guide précédent, un indicateur est nécessaire pour chaque requête API. Sélectionnons le niveau de population, indicateur 9 :

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=9

Ajout d’un seul paramètre

Si la requête API était envoyée comme ci-dessus sans aucun paramètre, l’API renverrait le niveau de population du Canada à une date arbitraire. Nous pouvons facilement trouver le niveau de population dans chaque province et territoire en ajoutant « &geo=provinces_territories » à la chaîne de requête. La requête API sera alors au format curl :

curl --location --request POST 'https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=9&geo=provinces_territories' \
--header 'x-api-key: API_KEY' \
--data-raw ''

Rappelez-vous de toujours remplacer API_KEY par votre clé API unique pour authentifier votre requête API. De là, il est facile d’ajouter d'autres paramètres à la fin de la chaîne de requête, il suffit d’utiliser le symbole « & » pour chaque paramètre. Notez que certaines combinaisons de paramètres (et de filtres — voir plus loin) renverront une réponse vide. Cela indique que le Carrefour de données ne dispose pas des données demandées. Pour identifier où les données n’existent pas, envisagez de construire vos requêtes API paramètre par paramètre, en testant la réponse au fur et à mesure.

Exemples de paramètres uniques

Niveau de population au Canada pour les personnes âgées de 25 à 54 ans :

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=9&age=25-54

Pour trouver le taux de chômage désaisonnalisé :

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=5&seasonality=seasonally adjusted

Pour trouver le salaire hebdomadaire moyen :

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=11

Ajout de paramètres multiples

Maintenant que vous êtes familiaré avec l’utilisation de paramètres uniques, nous pouvons passer à l’utilisation de paramètres multiples pour chaque requête. Pour sélectionner plusieurs paramètres, il suffit d’ajouter des chaînes de requête supplémentaires à vos points de terminaison en utilisant le signe « &» entre chaque chaîne. Par exemple :

Taux d’emploi dans chaque province et territoire pour les personnes âgées de 15 à 24 ans :

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=2&age=15-24&geo=provinces_territories

Sélection des dates

Jusqu'à présent, dans cette documentation, nos requêtes API ont porté sur des dates arbitraires, ce qui serait inutile pour toute requête réelle. La sélection des dates d’intérêt dans le Carrefour de données est plus délicate que les autres paramètres, car différents indicateurs interprètent les dates différemment, et la réponse dépendra du niveau d’agrégation des données (la valeur par défaut est mensuelle).

Les deux paramètres nommés « début » et « fin » permettent à l’utilisateur de demander des données pour une période donnée. Le Carrefour de données intègre les données de ses partenaires tous les mois, donc sélectionner un mois actuel déclenchera la réponse pour les données du mois précédent. De même, si vous sélectionnez des dates sans données historiques, l’API retournera les données disponibles les plus anciennes.

Prenons l’exemple du taux de chômage :

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=5&seasonality=seasonally adjusted

Si nous voulons trouver le taux de chômage en septembre 2021, nos dates de début et de fin doivent être comprises dans ce mois pour que l'API renvoie uniquement ce mois. Si nos dates se situent entre septembre 2021 et octobre 2021, l'API renverra deux enregistrements, un pour septembre et un pour octobre. Le jour exact du mois est sans importance. L'exemple suivant concerne le mois de septembre (notez le format AAAAMMJJ) :

https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=5&seasonality=seasonally adjusted&start=20210901&end=20210901

Sélection des dates pour les indicateurs de croissance

En vous référant à la documentation sur les indicateurs, vous verrez que certains indicateurs portent le nom « croissance ». Ces indicateurs utilisent les paramètres « début » et « fin » d’une manière différente et effectuent des calculs supplémentaires pour l’utilisateur. Par exemple, « Job Posting Growth Year over Year (Croissance des offres d’emploi d’une année à l’autre) », calcule la croissance annuelle de l’indicateur « Job Posting Counts (Nombre d’offres d’emploi) ». Le calcul prend la période sélectionnée avec le début et la fin, et compare la valeur de l’indicateur aux 12 mois précédents pour donner un taux de croissance (format ratio).

La requête API ci-dessous renvoie la croissance des offres d’emploi entre février 2022 et février 2021 :

curl --location --request POST 'https://lmic-datahub-prod-gw-d6ow9n6v.uc.gateway.dev/lmi?indicator=15&&start=20220201&end=20220201' \
--header 'x-api-key: API_KEY' \
--data-raw ''

La réponse :

{
    "data": [
        {
            "source": "Vicinity Jobs",
            "ref_date": "2022-02-28",
            "data_frequency": "monthly",
            "noc_code": "",
            "noc_level": null,
            "noc_title_en": "",
            "country": "Canada",
            "provinces_territories": null,
            "economic_regions_en": null,
            "census_division": null,
            "location": null,
            "indicator_name_en": "Year on year job postings growth",
            "indicator_value": 0.456
        }
    ],
    "meta": {
        "current_page": 1,
        "total_pages": 1,
        "per_page": 1000,
        "total_rows": 1
    }
}